<!DOCTYPE html>
<html lang="en">
  <head>
    <title>Migration  Reference</title>
    <link rel="stylesheet" type="text/css" href="css/jazzy.css" />
    <link rel="stylesheet" type="text/css" href="css/highlight.css" />
    <meta charset='utf-8'>
    <script src="js/jquery.min.js" defer></script>
    <script src="js/jazzy.js" defer></script>
    
  </head>
  <body>
    <a title="Migration  Reference"></a>
    <header>
      <div class="content-wrapper">
        <p><a href="index.html">IGListKit Docs</a> (98% documented)</p>
        <p class="header-right"><a href="https://github.com/Instagram/IGListKit"><img src="img/gh.png"/>View on GitHub</a></p>
      </div>
    </header>
    <div class="content-wrapper">
      <p id="breadcrumbs">
        <a href="index.html">IGListKit Reference</a>
        <img id="carat" src="img/carat.png" />
        Migration  Reference
      </p>
    </div>
    <div class="content-wrapper">
      <nav class="sidebar">
        <ul class="nav-groups">
          <li class="nav-group-name">
            <a href="Guides.html">Guides</a>
            <ul class="nav-group-tasks">
              <li class="nav-group-task">
                <a href="best-practices-and-faq.html">Best Practices and FAQ</a>
              </li>
              <li class="nav-group-task">
                <a href="generating-your-models-using-remodel.html">Generating your models using remodel</a>
              </li>
              <li class="nav-group-task">
                <a href="getting-started.html">Getting Started</a>
              </li>
              <li class="nav-group-task">
                <a href="iglistdiffable-and-equality.html">IGListDiffable and Equality</a>
              </li>
              <li class="nav-group-task">
                <a href="installation.html">Installation</a>
              </li>
              <li class="nav-group-task">
                <a href="migration.html">Migration</a>
              </li>
              <li class="nav-group-task">
                <a href="modeling-and-binding.html">Modeling and Binding</a>
              </li>
              <li class="nav-group-task">
                <a href="vision.html">VISION</a>
              </li>
              <li class="nav-group-task">
                <a href="working-with-core-data.html">Working with Core Data</a>
              </li>
              <li class="nav-group-task">
                <a href="working-with-uicollectionview.html">Working with UICollectionView</a>
              </li>
            </ul>
          </li>
          <li class="nav-group-name">
            <a href="Classes.html">Classes</a>
            <ul class="nav-group-tasks">
              <li class="nav-group-task">
                <a href="Classes/IGListAdapter.html">IGListAdapter</a>
              </li>
              <li class="nav-group-task">
                <a href="Classes/IGListAdapterUpdater.html">IGListAdapterUpdater</a>
              </li>
              <li class="nav-group-task">
                <a href="Classes/IGListBatchUpdateData.html">IGListBatchUpdateData</a>
              </li>
              <li class="nav-group-task">
                <a href="Classes/IGListBindingSectionController.html">IGListBindingSectionController</a>
              </li>
              <li class="nav-group-task">
                <a href="Classes/IGListCollectionView.html">IGListCollectionView</a>
              </li>
              <li class="nav-group-task">
                <a href="Classes/IGListCollectionViewLayout.html">IGListCollectionViewLayout</a>
              </li>
              <li class="nav-group-task">
                <a href="Classes/IGListGenericSectionController.html">IGListGenericSectionController</a>
              </li>
              <li class="nav-group-task">
                <a href="Classes/IGListIndexPathResult.html">IGListIndexPathResult</a>
              </li>
              <li class="nav-group-task">
                <a href="Classes/IGListIndexSetResult.html">IGListIndexSetResult</a>
              </li>
              <li class="nav-group-task">
                <a href="Classes/IGListMoveIndex.html">IGListMoveIndex</a>
              </li>
              <li class="nav-group-task">
                <a href="Classes/IGListMoveIndexPath.html">IGListMoveIndexPath</a>
              </li>
              <li class="nav-group-task">
                <a href="Classes.html#/c:objc(cs)IGListReloadDataUpdater">IGListReloadDataUpdater</a>
              </li>
              <li class="nav-group-task">
                <a href="Classes/IGListSectionController.html">IGListSectionController</a>
              </li>
              <li class="nav-group-task">
                <a href="Classes/IGListSingleSectionController.html">IGListSingleSectionController</a>
              </li>
            </ul>
          </li>
          <li class="nav-group-name">
            <a href="Constants.html">Constants</a>
            <ul class="nav-group-tasks">
              <li class="nav-group-task">
                <a href="Constants.html#/c:@IGListKitVersionNumber">IGListKitVersionNumber</a>
              </li>
              <li class="nav-group-task">
                <a href="Constants.html#/c:@IGListKitVersionString">IGListKitVersionString</a>
              </li>
            </ul>
          </li>
          <li class="nav-group-name">
            <a href="Enums.html">Enumerations</a>
            <ul class="nav-group-tasks">
              <li class="nav-group-task">
                <a href="Enums/IGListAdapterUpdateType.html">IGListAdapterUpdateType</a>
              </li>
              <li class="nav-group-task">
                <a href="Enums/IGListDiffOption.html">IGListDiffOption</a>
              </li>
              <li class="nav-group-task">
                <a href="Enums/IGListExperiment.html">IGListExperiment</a>
              </li>
            </ul>
          </li>
          <li class="nav-group-name">
            <a href="Protocols.html">Protocols</a>
            <ul class="nav-group-tasks">
              <li class="nav-group-task">
                <a href="Protocols/IGListAdapterDataSource.html">IGListAdapterDataSource</a>
              </li>
              <li class="nav-group-task">
                <a href="Protocols/IGListAdapterDelegate.html">IGListAdapterDelegate</a>
              </li>
              <li class="nav-group-task">
                <a href="Protocols/IGListAdapterMoveDelegate.html">IGListAdapterMoveDelegate</a>
              </li>
              <li class="nav-group-task">
                <a href="Protocols/IGListAdapterPerformanceDelegate.html">IGListAdapterPerformanceDelegate</a>
              </li>
              <li class="nav-group-task">
                <a href="Protocols/IGListAdapterUpdateListener.html">IGListAdapterUpdateListener</a>
              </li>
              <li class="nav-group-task">
                <a href="Protocols/IGListAdapterUpdaterDelegate.html">IGListAdapterUpdaterDelegate</a>
              </li>
              <li class="nav-group-task">
                <a href="Protocols/IGListBatchContext.html">IGListBatchContext</a>
              </li>
              <li class="nav-group-task">
                <a href="Protocols/IGListBindable.html">IGListBindable</a>
              </li>
              <li class="nav-group-task">
                <a href="Protocols/IGListBindingSectionControllerDataSource.html">IGListBindingSectionControllerDataSource</a>
              </li>
              <li class="nav-group-task">
                <a href="Protocols/IGListBindingSectionControllerSelectionDelegate.html">IGListBindingSectionControllerSelectionDelegate</a>
              </li>
              <li class="nav-group-task">
                <a href="Protocols/IGListCollectionContext.html">IGListCollectionContext</a>
              </li>
              <li class="nav-group-task">
                <a href="Protocols/IGListCollectionViewDelegateLayout.html">IGListCollectionViewDelegateLayout</a>
              </li>
              <li class="nav-group-task">
                <a href="Protocols/IGListCollectionViewLayoutCompatible.html">IGListCollectionViewLayoutCompatible</a>
              </li>
              <li class="nav-group-task">
                <a href="Protocols/IGListDiffable.html">IGListDiffable</a>
              </li>
              <li class="nav-group-task">
                <a href="Protocols/IGListDisplayDelegate.html">IGListDisplayDelegate</a>
              </li>
              <li class="nav-group-task">
                <a href="Protocols/IGListScrollDelegate.html">IGListScrollDelegate</a>
              </li>
              <li class="nav-group-task">
                <a href="Protocols/IGListSingleSectionControllerDelegate.html">IGListSingleSectionControllerDelegate</a>
              </li>
              <li class="nav-group-task">
                <a href="Protocols/IGListSupplementaryViewSource.html">IGListSupplementaryViewSource</a>
              </li>
              <li class="nav-group-task">
                <a href="Protocols/IGListTransitionDelegate.html">IGListTransitionDelegate</a>
              </li>
              <li class="nav-group-task">
                <a href="Protocols/IGListUpdatingDelegate.html">IGListUpdatingDelegate</a>
              </li>
              <li class="nav-group-task">
                <a href="Protocols/IGListWorkingRangeDelegate.html">IGListWorkingRangeDelegate</a>
              </li>
            </ul>
          </li>
          <li class="nav-group-name">
            <a href="Type%20Definitions.html">Type Definitions</a>
            <ul class="nav-group-tasks">
              <li class="nav-group-task">
                <a href="Type%20Definitions/IGListCollectionScrollingTraits.html">IGListCollectionScrollingTraits</a>
              </li>
              <li class="nav-group-task">
                <a href="Type%20Definitions.html#/c:IGListUpdatingDelegate.h@T@IGListCollectionViewBlock">IGListCollectionViewBlock</a>
              </li>
              <li class="nav-group-task">
                <a href="Type%20Definitions.html#/c:IGListUpdatingDelegate.h@T@IGListItemUpdateBlock">IGListItemUpdateBlock</a>
              </li>
              <li class="nav-group-task">
                <a href="Type%20Definitions.html#/c:IGListUpdatingDelegate.h@T@IGListObjectTransitionBlock">IGListObjectTransitionBlock</a>
              </li>
              <li class="nav-group-task">
                <a href="Type%20Definitions.html#/c:IGListUpdatingDelegate.h@T@IGListReloadUpdateBlock">IGListReloadUpdateBlock</a>
              </li>
              <li class="nav-group-task">
                <a href="Type%20Definitions.html#/c:IGListSingleSectionController.h@T@IGListSingleSectionCellConfigureBlock">IGListSingleSectionCellConfigureBlock</a>
              </li>
              <li class="nav-group-task">
                <a href="Type%20Definitions.html#/c:IGListSingleSectionController.h@T@IGListSingleSectionCellSizeBlock">IGListSingleSectionCellSizeBlock</a>
              </li>
              <li class="nav-group-task">
                <a href="Type%20Definitions.html#/c:IGListUpdatingDelegate.h@T@IGListToObjectBlock">IGListToObjectBlock</a>
              </li>
              <li class="nav-group-task">
                <a href="Type%20Definitions.html#/c:IGListAdapter.h@T@IGListUpdaterCompletion">IGListUpdaterCompletion</a>
              </li>
              <li class="nav-group-task">
                <a href="Type%20Definitions.html#/c:IGListUpdatingDelegate.h@T@IGListUpdatingCompletion">IGListUpdatingCompletion</a>
              </li>
            </ul>
          </li>
          <li class="nav-group-name">
            <a href="Functions.html">Functions</a>
            <ul class="nav-group-tasks">
              <li class="nav-group-task">
                <a href="Functions.html#/c:@F@IGListDiff">IGListDiff</a>
              </li>
              <li class="nav-group-task">
                <a href="Functions.html#/c:@F@IGListDiffExperiment">IGListDiffExperiment</a>
              </li>
              <li class="nav-group-task">
                <a href="Functions.html#/c:@F@IGListDiffPaths">IGListDiffPaths</a>
              </li>
              <li class="nav-group-task">
                <a href="Functions.html#/c:@F@IGListDiffPathsExperiment">IGListDiffPathsExperiment</a>
              </li>
              <li class="nav-group-task">
                <a href="Functions.html#/c:IGListExperiments.h@F@IGListExperimentEnabled">IGListExperimentEnabled</a>
              </li>
            </ul>
          </li>
          <li class="nav-group-name">
            <a href="Structs.html">Structures</a>
            <ul class="nav-group-tasks">
              <li class="nav-group-task">
                <a href="Structs/IGListCollectionScrollingTraits.html">IGListCollectionScrollingTraits</a>
              </li>
            </ul>
          </li>
        </ul>
      </nav>
      <article class="main-content">
        <section>
          <section class="section">
            
            <h1 id='migration' class='heading'>Migration</h1>

<p>This guide provides details for how to migrate between major versions of <code>IGListKit</code>.</p>
<h2 id='from-2-x-to-3-x' class='heading'>From 2.x to 3.x</h2>

<p>For details on all changes in IGListKit 3.0.0, please see the <a href="https://github.com/Instagram/IGListKit/releases/tag/3.0.0">release notes</a>. </p>

<blockquote>
<p><strong>NOTE:</strong> This release contains <em>a lot</em> of improvements and source-breaking API changes, especially for Swift clients. These are all noted in the full <a href="https://github.com/Instagram/IGListKit/releases/tag/3.0.0">release notes</a>.</p>
</blockquote>
<h3 id='q-ig-q-prefix-removed-for-swift' class='heading'><q>IG</q> prefix removed for Swift</h3>

<p>We have improved how <code>IGListKit</code> APIs get imported into Swift. The <code>IG</code> prefix has been removed for Swift clients. For example, <code><a href="Classes/IGListSectionController.html">IGListSectionController</a></code> becomes <code>ListSectionController</code> instead. Along with other interoperability improvements, this makes <code>IGListKit</code> more readable in Swift.</p>

<p>To migrate, use Xcode&rsquo;s Find navigator (command-3), search for <code>IGList</code>, and replace with <code>List</code>.</p>
<h3 id='code-iglistsectiontype-code-removed' class='heading'><code>IGListSectionType</code> removed</h3>

<p>In order to make building section controllers even easier, we removed the protocol and absorbed all of the methods into <code><a href="Classes/IGListSectionController.html">IGListSectionController</a></code> with default implementations.</p>

<ul>
<li><code>numberOfItems</code> returns 1 item</li>
<li><code>didUpdateToObject:</code> and <code>didSelectItemAtIndex:</code> do nothing</li>
<li><code>sizeForItemAtIndex:</code> returns <code>CGSizeZero</code></li>
<li><code>cellForItemAtIndex:</code> asserts (you must override this method)</li>
</ul>

<p>In Objective-C, all you need to do is find &amp; remove all uses of <code>IGListSectionType</code>. This includes <code><a href="Classes/IGListSectionController.html">IGListSectionController</a></code> and <code><a href="Protocols/IGListAdapterDataSource.html">IGListAdapterDataSource</a></code> implementations.</p>

<p>In Swift, you will also need to add <code>override</code> keywords to all methods.</p>

<p>The compiler should catch all instances that need fixed.</p>
<h3 id='code-iglistbindingsectioncontroller-code' class='heading'><code><a href="Classes/IGListBindingSectionController.html">IGListBindingSectionController</a></code></h3>

<p>If you were using <code>IGListDiff(...)</code> <em>inside</em> a section controller to compute diffs for cells, we recommend that you start using <code><a href="Classes/IGListBindingSectionController.html">IGListBindingSectionController</a></code> which wraps this behavior in an elegant and tested API.</p>
<h3 id='removed-code-iglistcollectionview-code' class='heading'>Removed <code><a href="Classes/IGListCollectionView.html">IGListCollectionView</a></code></h3>

<p>You can simply find regex <code>IGListCollectionView([ |\*|\(])</code> and replace with regex <code>UICollectionView$1</code> in your project to fix this.</p>

<p><img src="https://raw.githubusercontent.com/Instagram/IGListKit/master/Resources/replace-iglistcollectionview.png" alt="Replace IGListCollectionView"></p>
<h3 id='removed-code-iglistgridcollectionviewlayout-code' class='heading'>Removed <code>IGListGridCollectionViewLayout</code></h3>

<p>Start using <code><a href="Classes/IGListCollectionViewLayout.html">IGListCollectionViewLayout</a></code> instead of <code>IGListGridCollectionViewLayout</code>.</p>

<ul>
<li><code>scrollDirection</code> is not yet supported. If you need horizontal scrolling, please use <code>UICollectionViewFlowLayout</code> or file an issue.</li>
<li>Set <code>minimumLineSpacing</code> on your <a href="https://github.com/Instagram/IGListKit/blob/master/Source/IGListSectionController.h#L59-L64">section controllers</a> instead of the layout</li>
<li>Set <code>minimumInteritemSpacing</code> on your <a href="https://github.com/Instagram/IGListKit/blob/master/Source/IGListSectionController.h#L66-L71">section controllers</a> instead of the layout</li>
<li>Return the size of your cells in <a href="https://github.com/Instagram/IGListKit/blob/master/Source/IGListSectionController.h#L48">sizeForItemAtIndex:</a> instead of setting it on the layout.</li>
</ul>
<h3 id='item-mutations-must-be-wrapped-in-code-iglistcollectioncontext-performbatchanimated-completion-code' class='heading'>Item mutations must be wrapped in <code>-[IGListCollectionContext performBatchAnimated:completion:]</code></h3>

<p>To fix some rare crashes, all item mutations must now be performed inside a batch block and done on the <code><a href="Protocols/IGListBatchContext.html">IGListBatchContext</a></code> object instead.</p>

<p><strong>Objective-C</strong></p>
<pre class="highlight objective_c"><code><span class="c1">// OLD
</span><span class="n">self</span><span class="p">.</span><span class="n">expanded</span> <span class="o">=</span> <span class="nb">YES</span><span class="p">;</span>
<span class="p">[</span><span class="n">self</span><span class="p">.</span><span class="n">collectionContext</span> <span class="nf">insertInSectionController</span><span class="p">:</span><span class="n">self</span> <span class="nf">atIndexes</span><span class="p">:[</span><span class="n">NSIndexSet</span> <span class="nf">indexSetWithIndex</span><span class="p">:]];</span>

<span class="c1">// NEW
</span><span class="p">[</span><span class="n">self</span><span class="p">.</span><span class="n">collectionContext</span> <span class="nf">performBatchAnimated</span><span class="p">:</span><span class="nb">YES</span> <span class="nf">updates</span><span class="p">:</span><span class="o">^</span><span class="p">(</span><span class="n">id</span><span class="o">&lt;</span><span class="n">IGListBatchContext</span><span class="o">&gt;</span> <span class="n">batchContext</span><span class="p">)</span> <span class="p">{</span>
  <span class="n">self</span><span class="p">.</span><span class="n">expanded</span> <span class="o">=</span> <span class="nb">YES</span><span class="p">;</span>
  <span class="p">[</span><span class="n">batchContext</span> <span class="nf">insertInSectionController</span><span class="p">:</span><span class="n">self</span> <span class="nf">atIndexes</span><span class="p">:[</span><span class="n">NSIndexSet</span> <span class="nf">indexSetWithIndex</span><span class="p">:</span><span class="mi">1</span><span class="p">]];</span>
<span class="p">}</span> <span class="n">completion</span><span class="o">:</span><span class="nb">nil</span><span class="p">];</span>
</code></pre>

<p><strong>Swift</strong></p>
<pre class="highlight swift"><code><span class="c1">// OLD</span>
<span class="n">expanded</span> <span class="o">=</span> <span class="kc">true</span>
<span class="n">collectionContext</span><span class="p">?</span><span class="o">.</span><span class="nf">insert</span><span class="p">(</span><span class="nv">in</span><span class="p">:</span> <span class="k">self</span><span class="p">,</span> <span class="nv">at</span><span class="p">:</span> <span class="p">[</span><span class="mi">0</span><span class="p">])</span>

<span class="c1">// NEW</span>
<span class="n">collectionContext</span><span class="p">?</span><span class="o">.</span><span class="nf">performBatch</span><span class="p">(</span><span class="nv">animated</span><span class="p">:</span> <span class="kc">true</span><span class="p">,</span> <span class="nv">updates</span><span class="p">:</span> <span class="p">{</span> <span class="p">(</span><span class="n">batchContext</span><span class="p">)</span> <span class="k">in</span>
  <span class="k">self</span><span class="o">.</span><span class="n">expanded</span> <span class="o">=</span> <span class="kc">true</span>
  <span class="n">batchContext</span><span class="o">.</span><span class="nf">insert</span><span class="p">(</span><span class="nv">in</span><span class="p">:</span> <span class="k">self</span><span class="p">,</span> <span class="nv">at</span><span class="p">:</span> <span class="p">[</span><span class="mi">0</span><span class="p">])</span>
<span class="p">})</span>
</code></pre>

<p>Make sure that your model changes occur <strong>inside the update block</strong>, alongside the context methods.</p>
<h2 id='from-1-x-to-2-x' class='heading'>From 1.x to 2.x</h2>

<p>For details on all changes in <code>IGListKit</code> 2.0.0, please see the <a href="https://github.com/Instagram/IGListKit/releases/tag/2.0.0">release notes</a>.</p>
<h3 id='code-iglistdiffable-code-conformance' class='heading'><code><a href="Protocols/IGListDiffable.html">IGListDiffable</a></code> Conformance</h3>

<p>If you relied on the default <code>NSObject&lt;IGListDiffable&gt;</code> category, you will need to add <code><a href="Protocols/IGListDiffable.html">IGListDiffable</a></code> conformance to each of your models. To get things working as they did in 1.0, simply add the following to each of your models:</p>

<p><strong>Objective-C</strong></p>
<pre class="highlight objective_c"><code><span class="cp">#import &lt;IGListDiffKit/IGListDiffable.h&gt;
</span>
<span class="c1">// Header
</span><span class="k">@interface</span> <span class="nc">MyModel</span> <span class="o">&lt;</span><span class="n">IGListDiffable</span><span class="o">&gt;</span>

<span class="c1">// Implementation
</span><span class="o">-</span> <span class="p">(</span><span class="n">id</span><span class="o">&lt;</span><span class="n">NSObject</span><span class="o">&gt;</span><span class="p">)</span><span class="n">diffIdentifier</span> <span class="p">{</span>
  <span class="k">return</span> <span class="n">self</span><span class="p">;</span>
<span class="p">}</span>

<span class="o">-</span> <span class="p">(</span><span class="n">BOOL</span><span class="p">)</span><span class="n">isEqualToDiffableObject</span><span class="o">:</span><span class="p">(</span><span class="n">id</span><span class="o">&lt;</span><span class="n">IGListDiffable</span><span class="o">&gt;</span><span class="p">)</span><span class="n">object</span> <span class="p">{</span>
  <span class="k">return</span> <span class="p">[</span><span class="n">self</span> <span class="nf">isEqual</span><span class="p">:</span><span class="n">object</span><span class="p">];</span>
<span class="p">}</span>
</code></pre>

<p><strong>Swift</strong></p>
<pre class="highlight swift"><code><span class="kd">import</span> <span class="kt">IGListKit</span>

<span class="kd">extension</span> <span class="kt">MyModel</span><span class="p">:</span> <span class="kt">ListDiffable</span> <span class="p">{</span>
  <span class="kd">func</span> <span class="nf">diffIdentifier</span><span class="p">()</span> <span class="o">-&gt;</span> <span class="kt">NSObjectProtocol</span> <span class="p">{</span>
    <span class="k">return</span> <span class="k">self</span>
  <span class="p">}</span>

  <span class="kd">func</span> <span class="nf">isEqual</span><span class="p">(</span><span class="n">toDiffableObject</span> <span class="nv">object</span><span class="p">:</span> <span class="kt">ListDiffable</span><span class="p">?)</span> <span class="o">-&gt;</span> <span class="kt">Bool</span> <span class="p">{</span>
    <span class="k">return</span> <span class="nf">isEqual</span><span class="p">(</span><span class="n">object</span><span class="p">)</span>
  <span class="p">}</span>
<span class="p">}</span>
</code></pre>

<p>However we recommend writing more thorough identity and equality checks. Check out our guide to <a href="https://instagram.github.io/IGListKit/iglistdiffable-and-equality.html">IGListDiffable and Equality</a> for more info.</p>

          </section>
        </section>
        <section id="footer">
          <p>&copy; 2019 <a class="link" href="https://twitter.com/fbOpenSource" target="_blank" rel="external">Instagram</a>. All rights reserved. (Last updated: 2019-11-20)</p>
          <p>Generated by <a class="link" href="https://github.com/realm/jazzy" target="_blank" rel="external">jazzy ♪♫ v0.12.0</a>, a <a class="link" href="https://realm.io" target="_blank" rel="external">Realm</a> project.</p>
        </section>
      </article>
    </div>
  </body>
</div>
</html>
